Skip to content

Conversation

@github-actions
Copy link
Contributor

@github-actions github-actions bot commented Nov 25, 2025

Backport of #64529 to release/10.0

/cc @javiercn

Fix Blazor navigation error caused by metadata comments in logical tree

Prevent metadata comments from becoming logical elements during rendering

Description

This PR fixes a bug where Blazor metadata comments (such as WebAssembly options, component state, and initializers) were being converted into logical elements during the initial render. When these comments were later removed from the DOM during component discovery, they remained in the logical tree as orphaned references, causing insertBefore errors during subsequent navigation between different render modes.

The fix modifies toLogicalElement() in LogicalElements.ts to skip metadata comments before they enter the logical tree, using a new isMetadataComment() helper function in ComponentDescriptorDiscovery.ts that identifies all Blazor metadata comment types.

Fixes #64522, #64472

Customer Impact

Users experience JavaScript errors and navigation failures when navigating between pages with different render modes (InteractiveServer, InteractiveWebAssembly, or InteractiveAuto) in Blazor Web Apps. The error manifests as:

  • Uncaught TypeError: Cannot read properties of null (reading 'insertBefore')
  • Failed page transitions requiring full browser refresh
  • Broken user experience in production applications

This particularly affects applications using:

  • PageTitle components with different render modes
  • Navigation between InteractiveWebAssembly and InteractiveServer pages
  • Any scenario mixing render modes in a Blazor United application

Regression?

  • Yes
  • No

This is a regression introduced in .NET 10.0 when the WebAssembly options discovery mechanism was added. The <!--Blazor-WebAssembly:{...}--> comment is new to v10.0 and was not present in v9.0. The toLogicalElement() function was indiscriminately converting all nodes including these new metadata comments into logical elements, which caused the orphaning issue when the comments were removed from the DOM.

Risk

  • High
  • Medium
  • Low

Justification:

  • The fix is surgical and only affects the initial logical tree construction
  • It prevents a specific category of nodes (metadata comments) from entering the logical tree
  • Metadata comments were never intended to be logical elements - they are consumed during discovery
  • The fix aligns behavior with design intent: these comments are transient markers, not components
  • Extensively validated with two independent reproduction cases from separate bug reports
  • No changes to core rendering logic, only to node filtering during tree construction
  • The isMetadataComment() function uses explicit prefix matching with well-defined comment formats

Verification

  • Manual (required)
  • Automated

Manual verification completed:

  1. BlazorApp10 (Issue .Net 10 Blazor Enhanced Navigation in WASM fails due to no PageTitle #64522): Validated navigation between InteractiveServer pages with/without PageTitle components, and InteractiveWebAssembly pages. Multiple navigation cycles completed without errors.

  2. BugReportApp (Issue .NET 10 Blazor navigation from wasm to interactive server broken #64472): Validated navigation between InteractiveWebAssembly → InteractiveServer → InteractiveWebAssembly. Both directions work correctly with SignalR connections established properly.

Packaging changes reviewed?

  • Yes
  • No
  • N/A

This is a JavaScript/TypeScript code change only. No packaging changes required.


When servicing release/2.3

  • Make necessary changes in eng/PatchConfig.props

@dotnet-policy-service
Copy link
Contributor

Looks like this PR hasn't been active for some time and the codebase could have been changed in the meantime.
To make sure no conflicting changes have occurred, please rerun validation before merging. You can do this by leaving an /azp run comment here (requires commit rights), or by simply closing and reopening.

@dotnet-policy-service dotnet-policy-service bot added the pending-ci-rerun When assigned to a PR indicates that the CI checks should be rerun label Dec 3, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

pending-ci-rerun When assigned to a PR indicates that the CI checks should be rerun

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants